Celestin Apprentice 2/Apprentice-Release2.iso/Source Code/C/Libraries/hash/md5.1

Text File | 1994-03-25 | 9.2 KB | 338 lines | [TEXT/R*ch]

.\" @(#)md5.1    10.1 3/25/94 08:04:09
.\"
.\" This man page was written by:
.\"
.\"     Landon Curt Noll  ([e-mail])    chongo <was here> /\../\
.\"
.\" This man page has been placed in the public domain.  Please do not
.\" copyright this man page.
.\"
.\" LANDON CURT NOLL DISCLAIMS ALL WARRANTIES WITH  REGARD  TO
.\" THIS  SOFTWARE,  INCLUDING  ALL IMPLIED WARRANTIES OF MER-
.\" CHANTABILITY AND FITNESS.  IN NO EVENT SHALL  LANDON  CURT
.\" NOLL  BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL
.\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM  LOSS  OF
.\" USE,  DATA  OR  PROFITS, WHETHER IN AN ACTION OF CONTRACT,
.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR  IN
.\" CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.\" See md5drvr.c for version and modification history.
.\"
.TH MD5 1  LOCAL
.SH NAME
md5 \- RSA Data Security, Inc. MD5 Message-Digest Algorithm
.SH SYNOPSIS
.BR md5 \ [
.BR \-cdhiqtx \ ][
.BR \-p prefix\ ][
.BR \-P prfile\ ][
.BR \-s str\ ]
file\ ...
.SH DESCRIPTION
The
.B md5
utility implements the
RSA Data Security, Inc. MD5 Message-Digest Algorithm (\fIMD5\fP).
It produces 128-bit MD5 Digests of files, strings or data
read on stdin.
If no
.B file
is given, and
no string is to be digested (\fB\-s\fP)
then stdin will be digested.
By default, a digests are printed as 40 hex characters without a leading
.IR 0x .
.PP
The
algorithm takes as input an input message of arbitrary length and
produces as output a 128-bit ``fingerprint'' or ``message digest'' of the
input.
It is conjectured that it is computationally infeasible to
produce two messages having the same message digest, or to produce
any message having a given prespecified target message digest. The
.I MD5
algorithm is intended for digital signature applications, where a
large file must be ``compressed'' in a secure manner before being
encrypted with a private (secret) key under a public-key cryptosystem
such as RSA.
.PP
If a
.B str
(string) argument is given, then the digest for
.BR str ,
followed by a space, followed by
.B str
enclosed double quotes is written to stdout.
Any
.B file
arguments are ignored.
.PP
If one or more
.B file
if given, a separate digest if produced for each file.
By default,
.B file
digests are followed by a space and the filename.
.PP
If no
.B str
or
.B file
arguments are given, then a digest of stdin is written to stdout.
.PP
.TP
.B \-c
Print C style hex digests with a leading \fI0x\fP.
.TP
.B \-d
Compute dual digests.
.sp
Data is divided into two streams and digested separately.
Each successive octet is assigned an index starting with 0.
The even stream consists of octets with even indices.
The odd stream consists of octets with odd indices.
The even stream digest, followed by a space, followed by
the odd stream digest is written to stdout.
.TP
.B \-h
Print a help and usage message.
.TP
.B \-i
Compute inode digests of files.
.sp
Prepend the filename and various inode information to the file data
being digested.
The inode information prepended includes information
such as the device (\fIst_dev\fP),
inode number (\fIst_ino\fP),
mode (\fIst_mode\fP),
link count (\fIst_nlink\fP),
uid (\fIst_uid\fP),
gid (\fIst_gid\fP),
size (\fIst_size\fP),
modification time (\fIst_mtime\fP) and
change time (\fIst_ctime\fP).
The prepended data is padded with zeros to make it a multiple of 64
bytes long.
Both a
.BR stat (2)
and a
.BR lstat (2)
information are both used.
.sp
The \fB\-i\fP flag allows one to include various inode information in
the digest.
This option is useful in detecting file tampering.
For example, the following will produce different digests:
.sp
.in +0.5i
.nf
md5 \-i /tmp/chongo
cp /tmp/chongo /tmp/was_here
\^... misc funny business ...
cp /tmp/was_here /tmp/chongo
md5 \-i /tmp/chongo
.fi
.in -0.5i
.sp
Note that a \fB\-i\fP digest is portable to other systems.
This is because inode information will likely change as the
contents of a file are copied from machine to machine.
.sp
To mark a \fB\-i\fP digest as a special value, \fI.0\fP is
prepended onto the digest output.
.sp
One may only compute inode digests of files.
Use of
.B \-i
disables reading from stdin.
The
.B \-i
flag is not compatible with
.BR \-s .
.TP
.BI \-p prefix
.TP
.BI \-P prfile
Insert a prefix into the data to be digested.
.sp
By using \fB\-p\fP\fIprefix\fP, one may prepend any set of data with a
string.
The digest produced is equivalent to digest that is
produced with the string pretended to the data.
Thus the following two commands produce the same digest:
.sp
.in +0.5i
.nf
md5 \-p curds \-s whey
md5 \-s curdswhey
.fi
.in -0.5i
.sp
By use of the \fB\-P\fP\fIprfile\fP interface, one may prepend using
up to the 32k of a file.
This interface allows one to prepend using binary data.
The following produces the same digest:
.sp
.in +0.5i
.nf
md5 \-P /usr/bin/awk /bin/ls
dd if=/usr/bin/awk of=/tmp/foo bs=32k count=1
cat /tmp/foo /bin/ls > /tmp/ls
md5 /tmp/ls
.fi
.in -0.5i
.sp
Knowledge of the original prepend data is only kept in
the digest.
Thus one may use the prepend string as a ``salt'' making it intractable
for someone else to reproduce the digest of a file without knowledge
of the prepend data.
.sp
For sightly faster performance, use prepend data that is
a multiple of 64 bytes long.
The easy way to do this is to use \fB-P\fP on a file that is at least 32k
bytes in length.
.sp
This feature works in conjunction all modes of operation except
the \fB\-t\fP and \fB\-x\fP modes.
.TP
.B \-q
Output only digests.
The filename or string will not be written to stdout.
.TP
.BR \-s str
Digest \fIstr\fP as if it were a string.
.sp
The trailing NUL byte is not digested.
No files are digested.
The \fIstr\fP is written to stdout enclosed in double quotes.
.TP
.BR \-t
Time the user cpu seconds needed to digest several megabytes of data.
The number of megabytes,
followed by the digest produced,
followed by the number of user cpu seconds
followed by the number of characters per user second is written to stdout.
.sp
On some systems with certain virtual memory characteristics,
you may need to run the performance test several times, ignoring the
first result.
The default amount of data tested is 16 megabytes.
On some systems, this amount may differ.
One may change the number of megabytes processed by changing the value of
TEST_MEG in the file md5drvr.c and recompiling.
.TP
.BR \-v
Print the version.
.TP
.BR \-x
Perform an extended standard SHS test suite.
.sp
The test suite will first look in the current directory for
.IR file1 .
If it is not found, it will look in ${DESTDIR} (usually
.IR /usr/local/lib/md5 ).
It is assumes that
.I file2
is in the same location as
.sp
The standard test suite been extended.
The initial string now says:
.sp
.in +0.5i
.nf
md5 test suite results
.fi
.in -0.5i
.sp
instead of:
.sp
.in +0.5i
.nf
SHA test suite results
.fi
.in -0.5i
.sp
to reflect the utility name instead of the algorithm implemented.
This also helps distinguish this version from much older
versions which did not have the
.B -v
flag.
Also the original test file
.I foo
which contained the string  "\fIabc\fP" (with no newline) was renamed
.IR file1 .
.SH "SEE ALSO"
.BR shs (1),
.BR stat (2),
.BR lstat (2)
.SH FILES
.nf
\^./file1            default test file location
\^./file2            default test file location
${DESTDIR}/file1    alternate test file location
${DESTDIR}/file2    alternate test file location
.fi
.sp
The typical value of ${DESTDIR} is \fI/usr/local/lib/md5\fP,
or \fI/usr/local/lib\fP.
.SH AUTHOR
.nf
Much of this code was written, re-written or modified by:

    Landon Curt Noll    ([e-mail])  /\\../\\

Part of this code code is based on code by Peter C. Gutmann.
.fi
.SH NOTICE
LANDON CURT NOLL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS.
IN NO EVENT SHALL LANDON CURT NOLL BE LIABLE FOR ANY SPECIAL, INDIRECT OR
CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
PERFORMANCE OF THIS SOFTWARE.
.PP
Parts of this code are:
.PP
Copyright (C) 1990, RSA Data Security, Inc. All rights reserved.
.PP
License to copy and use this software is granted provided that
it is identified as the "RSA Data Security, Inc. MD5 Message-
Digest Algorithm" in all material mentioning or referencing this
software or this function.
.PP
License is also granted to make and use derivative works
provided that such works are identified as "derived from the RSA
Data Security, Inc. MD5 Message-Digest Algorithm" in all
material mentioning or referencing the derived work.
.PP
RSA Data Security, Inc. makes no representations concerning
either the merchantability of this software or the suitability
of this software for any particular purpose.  It is provided "as
is" without express or implied warranty of any kind.
.PP
These notices must be retained in any copies of any part of this
documentation and/or software.
.SH BUGS
The command:
.sp
.in +0.5i
.nf
md5 -s '/\\"O/\\'
.fi
.in -0.5i
.sp
writes to stdout, the following line:
.sp
.in +0.5i
.nf
ae8b1f8db9eaa95693164bd224291da0 "/\\"O/\\"
.fi
.in -0.5i
.sp
The string written in double quotes by
.B \-s
may not be a valid string according to C or shell syntax.